<!-- Markdown => HTML -->
<h1>Axe Interpreter</h1>
<hr />
<h2>Table of Contents</h2>
<ul>
<li><a href="#synopsis">Synopsis</a><ul>
<li><a href="#synopsis_summary">Summary</a></li>
<li><a href="#synopsis_metadata">Metadata</a></li>
</ul>
</li>
<li><a href="#thanks-and-credits">Thanks and credits</a></li>
<li><a href="#running-this-program">Running this program</a><ul>
<li><a href="#running-this-program_quick-start">Quick start guide</a></li>
<li><a href="#running-this-program_source-code">Running the source code</a></li>
</ul>
</li>
<li><a href="#restrictions">Restrictions</a></li>
<li><a href="#tokens">Tokens</a><ul>
<li><a href="#tokens_system">System</a></li>
<li><a href="#tokens_screen-and-buffer">Screen and Buffer</a></li>
<li><a href="#tokens_control-blocks">Control Blocks</a></li>
<li><a href="#tokens_basic-math">Basic Math</a></li>
<li><a href="#tokens_drawing">Drawing</a></li>
<li><a href="#tokens_text">Text</a></li>
<li><a href="#tokens_data-and-storage">Data and Storage</a></li>
<li><a href="#tokens_meta">Meta</a></li>
</ul>
</li>
<li><a href="#misc">Misc</a><ul>
<li><a href="#misc_newlines-and-colons">Newlines and colons</a></li>
<li><a href="#misc_getkey-config">The getKey config file</a></li>
</ul>
</li>
<li><a href="#version">Version history and roadmap</a><ul>
<li><a href="#version_history">Version History</a></li>
<li><a href="#version-roadmap">Roadmap</a></li>
</ul>
</li>
</ul>
<hr />
<h2 id="synopsis">Synopsis</h2>
<h3 id="synopsis_summary">Summary</h3>
<p>Axe Interpreter is a version of Axe meant to be run on computers.  This is
currently under heavy development, and will currently allow only a <em>very</em> limited subset
of Axe to be used.  I created this program because I was...</p>
<ol>
<li>Bored.</li>
<li>Wanted to try making a decent cross-platform development platform for Axe.</li>
</ol>
<p>This program is written in Python, and should be compatible with all major
operating systems, provided they have Python installed.</p>
<h3 id="synopsis_metadata">Metadata</h3>
<p>Author:   Michael Lee <a href="&#109;&#97;&#105;&#108;&#116;&#111;&#58;&#109;&#105;&#99;&#104;&#97;&#101;&#108;&#46;&#108;&#101;&#101;&#46;&#48;&#120;&#50;&#97;&#64;&#103;&#109;&#97;&#105;&#108;&#46;&#99;&#111;&#109;">&#109;&#105;&#99;&#104;&#97;&#101;&#108;&#46;&#108;&#101;&#101;&#46;&#48;&#120;&#50;&#97;&#64;&#103;&#109;&#97;&#105;&#108;&#46;&#99;&#111;&#109;</a><br />
License:  GNU Lesser GPL<br />
Version:  0.2<br />
Released: December 22th, 2011</p>
<hr />
<h2 id="thanks-and-credits">Thanks and credits</h2>
<ul>
<li>Kevin Horowitz (a.k.a. Quigibo):<br />
    For making Axe Parser.</li>
<li>The Omnimaga Community:<br />
    For general support and inspiration</li>
<li>PLY (Python Lex Yacc):<br />
    For providing lexing and parsing tools</li>
<li>Pygame:<br />
    For graphics and pixel manipulation</li>
</ul>
<hr />
<h2 id="running-this-program">Running this program</h2>
<h3 id="running-this-program_quick-start-guide">Quick Start Guide</h3>
<p>You can run this program either as an executable or via the source code.
To run the exe, navigate to either the 'Windows' folder or the 'Linux' folder
(whichever is appropriate).</p>
<p>Double-click it to run the interpreter.  Two windows should pop up -- one is
the console or command prompt, while the other is a small white window.  Type 
in commands to the console to make them happen.  A full list of supported 
tokens can be found in this readme.  Note that drawing commands do not need
'DispGraph' in interpreter mode -- type <strong>@DRAW 0</strong> to turn this behavior off
and <strong>@DRAW 1</strong> to turn it back on.</p>
<p>To run axe code, type it into a txt file and drag it over the exe.  Running
8xp source code is currently unsupported.</p>
<h3 id="running-this-program_source-code">Running the source code</h3>
<p>You will need the following:</p>
<ul>
<li><a href="http://python.org">Python 2.7</a></li>
<li><a href="http://pygame.org">Pygame 1.9.1</a></li>
<li><a href="http://numpy.scipy.org">Numpy</a></li>
</ul>
<p>In addition, this program also uses <a href="http://www.dabeaz.com/ply/">PLY 3.4</a>, but 
you don't need to install that: it should be included.</p>
<p>This program is run via Command Prompt.  To run the interpreter, type:</p>
<pre><code>$ python main.py --interpret
</code></pre>
<p>To execute a program, type:</p>
<pre><code>$ python main.py myprogram.txt
</code></pre>
<p>If you want to test specific components of the program, type one of the below:</p>
<pre><code>$ python main.py --test lex
$ python main.py --test parse
$ python main.py --test io
</code></pre>
<hr />
<h2 id="restrictions">Restrictions and Limitations</h2>
<p>I only started working on this a few days ago.  There are loads of limitations
and restrictions.</p>
<ul>
<li>You can only use the variables A to Z</li>
<li>You can only use numbers.  Strings, hex, binary, etc. are not supported</li>
<li>You can't declare constants yet</li>
<li>Only a limited subset of tokens are currently implemented (see below)</li>
<li>No grayscale is supported.</li>
<li>Changing L6 will not change the buffer.</li>
<li>You cannot use Labels, gotos, subroutines, or returns.</li>
</ul>
<hr />
<h2 id="tokens">Tokens</h2>
<p>Currently, only a very limited subset of tokens are allowed.  Currently allowed
tokens are...</p>
<h3 id="tokens_system">System</h3>
<ul>
<li>Single-line comments</li>
<li>Multi-line comments</li>
<li>Pause <em>EXPR</em></li>
<li>getKey(<em>KEY</em>)</li>
<li>getKey(0)</li>
</ul>
<h3 id="tokens_screen-and-buffer">Screen and Buffer</h3>
<ul>
<li>DispGraph</li>
<li>ClrDraw</li>
<li>Horizontal +</li>
<li>Horizontal -</li>
<li>Vertical +</li>
<li>Vertical -</li>
</ul>
<h3 id="tokens_control-blocks">Control Blocks</h3>
<ul>
<li>If <em>EXPR</em></li>
<li>Else</li>
<li>ElseIf <em>EXPR</em></li>
<li>End</li>
<li>While <em>EXPR</em></li>
<li>Repeat <em>EXPR</em></li>
<li>For(<em>EXPR</em>)</li>
<li>For(<em>VAR</em>, <em>EXPR1</em>, <em>EXPR2</em>)</li>
</ul>
<h3 id="tokens_basic-math">Basic Math</h3>
<ul>
<li><em>VAR</em><br />
    Only variables A-Z</li>
<li>o^^<em>VAR</em><br />
    Returns the address of the variable</li>
<li><em>EXPR</em> -&gt; <em>VAR</em></li>
<li>-<em>EXPR</em></li>
<li><em>Expr1</em> + <em>EXPR2</em></li>
<li><em>Expr1</em> - <em>EXPR2</em></li>
<li><em>Expr1</em> * <em>EXPR2</em></li>
<li><em>Expr1</em> / <em>EXPR2</em></li>
<li><em>Expr1</em> ^ <em>EXPR2</em></li>
<li><em>Expr1</em> = <em>EXPR2</em></li>
<li><em>Expr1</em> != <em>EXPR2</em></li>
<li><em>Expr1</em> &lt;= <em>EXPR2</em></li>
<li><em>Expr1</em> =&gt; <em>EXPR2</em></li>
<li><em>Expr1</em> <code>&lt;</code> <em>EXPR2</em></li>
<li><em>Expr1</em> <code>&gt;</code> <em>EXPR2</em></li>
<li>rand</li>
</ul>
<h3 id="tokens_drawing">Drawing</h3>
<ul>
<li>Pxl-On(<em>X_, _Y</em>)</li>
<li>Pxl-Off(<em>X_, _Y</em>)</li>
<li>Pxl-Change(<em>X_, _Y</em>)</li>
<li>Pxl-Test(<em>X_, _Y</em>)</li>
<li>Line(<em>X1</em>, <em>Y1</em>, <em>X2</em>, <em>Y2</em>)</li>
<li>Rect(<em>X_, _Y</em>, <em>W_, _H</em>)</li>
<li>RectI(<em>X_, _Y</em>, <em>W_, _H</em>)</li>
</ul>
<h3 id="tokens_text">Text</h3>
<ul>
<li>Disp <em>EXPR</em><br />
    Currently prints to the command line.  Note that this will display
    numbers (&gt;Dec, &gt;Char, &gt;Tok, and &gt;Hex) are not yet implemented.  Using
    the imaginary 'i' for newline has not yet been implemented.</li>
</ul>
<h3 id="tokens_data-and-storage">Data and Storage</h3>
<ul>
<li>{<em>EXPR</em>}</li>
<li><em>EXPR</em> -&gt; {<em>EXPR</em>}</li>
<li>L1, L2, L3, L4, L5, L6<br />
    Currently, these pointers only exist so you can have legit lists.
    Modifying L3 or L6 will not currently change the main or the backbuffer.</li>
</ul>
<h3 id="tokens_meta">Meta</h3>
<p>Meta tokens are ones which are not implemented in Axe, but do stuff to this
interpreter in particular.  Meta tokens work in both in interpreter mode and 
while running a file.</p>
<ul>
<li>@EXIT<br />
    Ends the program in both interpreter and drawing mode.</li>
<li>@DRAW<br />
    If turned on, displays all drawing commands the moment they're called 
    without having to call <strong>DispGraph</strong>.  Off by default while running a text
    file, on by default in interpreter mode.  <strong>@DRAW 1</strong> to turn on, and 
    <strong>@DRAW 0</strong> to turn off.</li>
<li>@HELP<br />
    Displays a brief help message.</li>
<li>@ABOUT<br />
    Displays a brief message about this program.</li>
<li>@DEBUG<br />
    Displays extra info to the command line for debugging.  Type '@DEBUG 1' 
    to turn it on and '@DEBUG 0' to turn it off.  Off by default, you shouldn't
    need this token.</li>
<li>@OPEN<br />
    Open a file to try and run.  Usage:  <strong>@OPEN "filepath"</strong>.  This will 
    attempt to open a txt (not 8xp) file and run it directly from the
    interpreter.  You can also use this almost like an 'import' function or
    jury-rig together functions until support for them is up.</li>
</ul>
<hr />
<h2 id="misc">Misc.</h2>
<h3 id="misc_newlines-and-colons">Newlines and colons</h3>
<p>You can use both colons and newlines to signify the end of a line.  Therefore,</p>
<pre><code>If A:Pxl-On(10,20):End
</code></pre>
<p>...is equivalent to...</p>
<pre><code>If A
    Pxl-On(10,20)
End
</code></pre>
<h3 id="misc_getkey-config">The getKey config file</h3>
<p>Included should be a file named <em>keybindings.config</em>.  This needs to be in the
same directory as the executable or source code when run.  When you open it,
you should see some comments at the top, and a row of keys, like so:</p>
<pre><code>K_BACKSPACE        :   15
K_TAB              :   0
K_CLEAR            :   0
K_RETURN           :   09
K_PAUSE            :   0
K_ESCAPE           :   41
K_SPACE            :   0
</code></pre>
<p>This means that that <strong>getKey(15)</strong> will return 1 when the backspace key is 
held, <strong>getKey(9)</strong>  will return 1 when Enter is held, etc.  The tab, clear, 
pause, and spacebar keys are assigned a value of zero, which means that 
they will not register any getKey codes.  Feel free to edit this file as you
want.</p>
<hr />
<h2 id="version">Version history and roadmap</h2>
<h3 id="version_history">Version History</h3>
<ul>
<li>
<p>Version 0.2: December 22nd, 2011<br />
    Getkey, rudimentary pointers, L1-L6 buffers, and more drawing commands.
    Source and exe provided.</p>
</li>
<li>
<p>Version 0.1: December 21th, 2011<br />
    A quick release -- basically a rerelease of 0.0 in exe form.</p>
</li>
<li>
<p>Version 0.0: December 20th, 2011<br />
    Has only numbers, rudimentary drawing primitives, and 
    a few control structures.  Source only.</p>
</li>
</ul>
<h3 id="version-roadmap">Roadmap</h3>
<ul>
<li>Adding better memory handling, pointers, and constants.</li>
<li>Attempting to integrate the memory and Pygame buffers to each other</li>
<li>Adding more drawing commands</li>
<li>Adding more control structures</li>
<li>Optimizing and decreasing memory footprint</li>
<li>Grayscale</li>
</ul>

